
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  EGSnrc statdose manual
%  Copyright (C) 2021 National Research Council Canada
%
%  This file is part of EGSnrc.
%
%  EGSnrc is free software: you can redistribute it and/or modify it under
%  the terms of the GNU Affero General Public License as published by the
%  Free Software Foundation, either version 3 of the License, or (at your
%  option) any later version.
%
%  EGSnrc is distributed in the hope that it will be useful, but WITHOUT ANY
%  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
%  FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for
%  more details.
%
%  You should have received a copy of the GNU Affero General Public License
%  along with EGSnrc. If not, see <http://www.gnu.org/licenses/>.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%  Authors:         HCE McGowan, 1995
%                   Bruce Faddegon, 1995
%                   Charlie Ma, 1995
%
%  Contributors:    Dave Rogers
%                   Blake Walters
%                   Andrew Booth
%                   Frederic Tessier
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\documentclass[12pt,twoside]{article}

\setlength{\textwidth}{6.5in}
\setlength{\textheight}{9.25in}
\setlength{\oddsidemargin}{0.0in}
\setlength{\evensidemargin}{0.0in}
\setlength{\topmargin}{-0.6in}
\setlength{\parindent}{1.5em}
\setlength{\topsep}{0ex}
\setlength{\itemsep}{0ex}
  \setlength{\unitlength}{1in}
\thicklines

\newcommand{\Co}{$^{60}$Co}
\newcommand{\parsp}{~\hspace*{1.5em}}
\setlength{\parskip}{0.1in}
\setlength{\baselineskip}{0.4in}
\newcommand{\head}[1]{\begin{center}\begin{Large}{\bf #1}
                                              \end{Large}\end{center}}
\newcommand{\cen}[1]{\begin{center} #1 \end{center}                   }
\newcommand{\etal}{{\em et.al.}}
\newcommand{\etc}{{\em etc}}
\newcommand{\eg}{{\em e.g.}}
\newcommand{\ie}{{\em i.e.}}

\usepackage{hyperref}
\hypersetup{colorlinks=true, citecolor=blue, linkcolor=blue, filecolor=blue, urlcolor=blue}
\urlstyle{same}

%\input{/usr/local/latex2html/html.sty}
\usepackage{html}

%\input{epsf}
\usepackage{epsf}

%\input{psfig}

\usepackage{fancyhdr}
\renewcommand{\footrulewidth}{0.4pt}
\renewcommand{\headrulewidth}{0.4pt}

\lhead[\thepage~]{NRCC Report PIRS-0509(F)}
\rhead[STATDOSE for 3D dose distributions]{~\thepage}
\rfoot{{\rightmark}}
\lfoot{{\leftmark}}
\cfoot{}

\begin{document}

\begin{htmlonly}
For information about the authors and/or institutions involved with this
work, use the links provided in the author list.\\

\begin{rawhtml}
<br><br>
\end{rawhtml}

\begin{rawhtml}
<br><br>
\end{rawhtml}

Postscript versions of the entire paper are available.  You may have to
download the compressed version to disk, uncompress or gunzip them and
then read or print them.
\htmladdnormallink{(uncompressed version 475 kb)}{statdose.ps}
\htmladdnormallink{(compress version 115 kb)}{statdose.ps.Z}
\htmladdnormallink{(gzip version 90 kb)}{statdose.ps.gz}
\begin{rawhtml}
<br><br>
\end{rawhtml}

Use the Up button to get back to this page from within the document.
\begin{rawhtml}
<BR> <HR> <P>
\end{rawhtml}
\copyright
\htmladdnormallink{Copyright 2021, National Research Council of Canada}
\begin{rawhtml}
<br>
<BR> <HR> <P>
\end{rawhtml}
\end{htmlonly}

\pagestyle{empty}
%\markright{\verb+STATDOSE+ for 3D dose distributions~~~~~~last edited 22 Aug 1966
%~~~~printed \today \hfill page~~}

%\markboth{STATDOSE for 3D dose distributions}{NRCC Report PIRS-0509(F)}

\setcounter{page}{1}
\title{STATDOSE for 3D dose distributions}
\author{ H.C.E. McGowan, B.A. Faddegon and C-M Ma \\
Ionizing Radiation Standards\\
National Research Council of Canada,
Ottawa\\
}
\date{Printed: \today \\
NRCC Report PIRS-0509(F) (last edited: $Date: 2013/03/29 15:20:41 $)
\begin{latexonly}
\\
Source tex file is: {\tt \$OMEGA\_HOME/doc/statdose/statdose.tex}
\end{latexonly}
}
\maketitle

\pagenumbering{arabic}
\setlength{\parindent}{0em}

\begin{center}
\begin{Large}
{\bf Abstract}
\end{Large}
\end{center}
\verb+STATDOSE+ is an interactive program for analyzing 3-dimensional dose
distributions generated by DOSXYZ. This report describes the structure and
functions of STATDOSE, how to compile and run STATDOSE, and the input and
output requirements for plotting 1-dimensional dose distributions using
the {\em Grace} plotting package ({\tt xmgrace} command).


\newpage

\tableofcontents

\newpage

\pagestyle{fancy}
%\pagestyle{myheadings}
\setcounter{page}{1}

\section{Introduction}

\verb+STATDOSE+ is an interactive computer program for 3-dimensional dose
analysis and plotting 1-dimensional dose distributions using the {\em
Grace} plotting package. 3D dose data such as that generated using the
EGS4 user-code DOSXYZ [1], developed at NRCC for the OMEGA project, are
examples of typical dose data. \verb+STATDOSE+ functions include normalization,
rebinning, plotting and analysis of the dose distributions. Distributions
can also be compared both statistically and graphically.  Graphs to aid in
statistical analysis of the distributions, as well as both cross-plots and
depth-doses, are provided by STATDOSE.\\

\verb+STATDOSE+ was originally written by H.C.E. McGowan and B.A. Faddegon for
analyzing dose results generated by DOSXYZ and plotting dose distributions
through PLOT\_XVGR, a subroutine written by M. Barfels and D.W.O. Rogers.
Both programs were modified and new scripts were written in order to
compile and run \verb+STATDOSE+ on both SUN and Silicon Graphics machines. This
report is a shortened version of the original program report and revised
to reflect changes and additions. The following sections contain an
overview of \verb+STATDOSE+ and a user's manual. Programming documentation is not
included, as the source code, {\em statdose.mortran}, has extensive
in-line documentation.

In order to run STADOSE one should first install {\em Grace} plotting
package (providing the {\tt xmgrace} command).

\section{Description of STATDOSE}

\subsection{Files Related to STATDOSE}
\verb+STATDOSE+ was written in MORTRAN3, a FORTRAN preprocessor, on a UNIX
system. The executable code must be run on a UNIX system with the {\em Grace}
graphics package and facility for running C shell scripts.
Files which are essential to the operation of \verb+STATDOSE+ are as
follows:

\begin{itemize}
\item {\em statdose.mortran} (MORTRAN program)
\item {\tt STATDOSE} (C-shell script, used to run \verb+STATDOSE+)
\item {\em compile\_statdose} (C-shell script, used to compile \verb+STATDOSE+)
\item {\em plot\_xvgr.f} (FORTRAN program, used to invoke {\tt xmgrace} with
preset options)
\item {\em filename.3ddose} (files containing 3D dose-data generated by DOSXYZ)
\item {\em plot\_xvgr.par} (sample parameter file required by  {\em plot\_xvgr.f})
\item {\em plot\_xvgr.bat} (sample data file required by {\em plot\_xvgr.f})
\end{itemize}
Files which are left behind by the operation of \verb+STATDOSE+ are as follows:
\begin {itemize}
\item {\em plotname.xvparam} ({\tt xmgrace}  parameter file for a plot,
written by {\em plot\_xvgr.f})
\item {\em plotname.xvplt} ({\tt xmgrace}  data file for a plot,
written by {\em plot\_xvgr.f})
\item {\em xvgr\_script} (Bourne-shell script, written by {\em plot\_xvgr.f}
and used to invoke {\tt xmgrace} )
\end{itemize}


\subsection{Structure and Functions of {\em statdose.mortran}}

The {\em statdose.mortran} code is written in MORTRAN3  and consists of the main program, subroutines, and MORTRAN replacement macros. The code has the following structure:
\newline\\

\begin{picture}(6.5,2.75)(-3.25,0)
\put(-1,2.25){\framebox(2,.5){\shortstack{replacement macros \\(in order of call) }}}
\put(0,2.25){\line(0,-1){.25}}
\put(-1.5,1.5){\framebox(3,.5){\shortstack{global variable dictionary}}}
\put(0,1.5){\line(0,-1){.25}}
\put(-.75,.75){\framebox(1.5,.5){\shortstack{main program }}}
\put(0,.75){\line(0,-1){.25}}
\put(-2,0){\framebox(4,.5){\shortstack{subroutines in order of appearance }}}
\end{picture}\\

Documentation occurs at the beginning of each subroutine. There is also
extensive in-line commenting. Error checking of user input is minimal.

\subsubsection{Subroutines}

The \verb+STATDOSE+ subroutines coincide with the menus and sub-menus used for interactive parameter selection. Choosing an option during execution will cause a subroutine specific to that task to be called. Below is a list of the subroutines and corresponding menu options.
All subroutine names are italicized:
\begin{itemize}
\item {\em mainmenu}\ --Display Main menu
\begin{itemize}
\item {\em readdose}\ --Read in Dose Distributions
\item {\em statsmenu}\ --Display Statistical Analysis menu
\begin{itemize}
\item {\em stats}\ --Calculate Statistics
\end{itemize}
\item {\em normmenu}\ --Display Normalization menu
\begin{itemize}
\item {\em scale}\ --Rescale Distribution
\item {\em averagedose}\ --Normalize to Average Dose
\item {\em centralmax}\ --Normalize to Maximum Dose Along Central Axis
\item {\em specvoxel}\ --Normalize to Dose in a Specific Voxel
\item {\em denormalize}\ --Restore the Original Distribution Dose Array
\end{itemize}
\item {\em rebinning}\ --Rebin a Distribution
\item {\em plotmenu}\ --Plot curves from Distributions
\begin{itemize}
\item {\em plotdose}\ --Plot Profiles of one Distribution
\item {\em compareplot}\ --Compare Plot Profiles from Multiple Distributions
\end{itemize}
\item {\em save}\ --Save Distributions
\end{itemize}
\end{itemize}

There are also subroutines which perform tasks within the menu option subroutines.
\begin{itemize}
 \item {\em newlettercount}\ --Counts the Number of Letters in a Character String
\item {\em plotfreq}\ --Plots Frequency Distribution Graphs
\end{itemize}

More details are given in the documentation at the beginning of the MORTRAN code for each subroutine.

\subsection{Subroutine {\em Plot\_xvgr.f} }

{\em Plot\_xvgr.f} is a FORTRAN subroutine for setting various {\tt xmgrace}
plot parameters, and then creating files which pass this
information on to {\tt xmgrace} . {\tt xmgrace} produces a graph from
the information in the files. Documentation of {\em plot\_xvgr.f} is
located at the beginning of the Fortran code.  This subroutine is now
included in {\em statdose.mortran}.

\subsection{Scripts}

\subsubsection{{\em compile\_statdose} script}

{\em compile\_statdose'} is a script to MORTRAN and Fortran compile {\em
statdose.mortran}. Depending on what machine the program is running on the
executable file is saved as {\em statdose.\$my\_machine.exe} (\eg, on a
SUN SPARC machine \$my\_machine = ``sparc''). In order to run
\verb+STATDOSE+ on any machines one should compile \verb+STATDOSE+ on
those machines by issuing the following command:  \newline\\
\ \framebox[4cm]{\em {compile\_statdose}}

\subsubsection{{\em statdose} script}

The \verb+STATDOSE+ script executes {\em statdose.\$my\_machine.exe},
depending on what machine it is running on. Two data files, {\em
plot\_xvgr.par} and {\em plot\_xvgr.bat}, required for plotting in {\tt xmgrace}
 data format are linked to logical units 11 and 31,
respectively. The following command may be issued to execute {\em
statdose}:  \newline\\ \ \framebox[4cm]{\em{statdose}} to run the program
\newline\\ \section{Format of DOSXYZ 3D Dose Data  } \subsection{{\em
filename.3ddose format}} DOSXYZ is a general-purpose EGS4 user code,
developed for the OMEGA project,  to do Cartesian coordinate dose
calculations (see ``DOSXYZ User's Manual'' by Ma \etal (1995)). The 3D
dose data generated by DOSXYZ is stored in a file with extension {\em
.3ddose}. The simulation geometry and 3D dose results are stored the
following format:\\

\setlength{\parindent}{0em}
Row/Block 1 --- number of voxels in x,y,z directions (e.g., $n_x, n_y, n_z$)

Row/Block 2 --- voxel boundaries (cm) in x direction($ n_x$ +1 values)

Row/Block 3 --- voxel boundaries (cm) in y direction
($ n_y$ +1 values)

Row/Block 4 --- voxel boundaries (cm) in z direction
($ n_z$ +1 values)

Row/Block 5 --- dose values array ($ n_x  n_y  n_z$  values)

Row/Block 6 --- error values array (relative errors, $ n_x  n_y  n_z$  values)\\

General Rules of reading the dose and statistical uncertainty (error) results:

\begin{itemize}
\item read one by one (across columns) to get dose (error) readings in x direction
\item read every $(n_x)$-th value to get readings in y direction
\item read every $(n_xn_y)$-th value to get readings in z direction
\end{itemize}

It should be noted that \verb+STATDOSE+ is capable of analyzing dose
results of format described above, not confined to the dose results
generated by DOSXYZ only. This means that \verb+STATDOSE+ can be used to
analyze 1D, 2D, and 3D dose results generated by other programs so long as
the dose data files have the same format as described above. For 1D dose
results along x-axis, for instance, one can ouput the geometry and dose
data in the following format:\\

\setlength{\parindent}{0em}
Row/Block 1 --- number of voxels in x,y,z directions ( $n_x, 1, 1$ )

Row/Block 2 --- voxel boundaries (cm) in x direction ($ n_x$ +1 values)

Row/Block 3 --- voxel boundaries (cm) in y direction (2 values)


Row/Block 4 --- voxel boundaries (cm) in z direction (2 values)

Row/Block 5 --- dose values ($ n_x$ values)

Row/Block 6 --- error values  ( $ n_x $  values)

\subsection{A Sample {\em filename.3ddose} File}
The following Table shows a sample 3D dose data and the file format. The doses are scored for a cubic geometry consisting of  4 x 4 x 4 voxels. Each voxel has a volume of  8 x 8 x 8 cm$^3$.
The center of voxel (2,1,3) has coordinates (-4,-12,4). The dose in the voxel is 6.0, and is shown in bold face in the above table.
\newline\\
{\scriptsize
\begin{tabular}[t]{||p{1.5cm}|p{2cm}|p{2cm}|p{2cm}|p{2cm}|p{2cm}||} \hline\hline
Row(block) & \multicolumn{5}{c||}{Column Number} \\ \cline{2-6}

Number &  1 &        2 &         3       & 4      &  5 \\ \hline
& & & & & \\

1 ~~~~~(1) &    4       &      4       &    4  &  & \\
& & & & & \\

2 ~~~~~(2)&   -16.0000 &    -8.0000 &    0.0000 &    8.0000 &   16.0000 \\
3 ~~~~~(3)&   -16.0000 &    -8.0000 &    0.0000 &    8.0000 &   16.0000  \\
4 ~~~~~(4)&   -16.0000 &    -8.0000 &    0.0000 &    8.0000 &   16.0000 \\
& & & & & \\

5 ~~~~~(5) &     1.0000 &    2.0000 &    2.0000 &    1.0000 &    2.0000\\
6 &     8.0000 &    8.0000 &    2.0000  &   2.0000 &    8.0000\\
7 &     8.0000 &    2.0000 &    1.0000 &    2.0000 &    2.0000\\
8 &     1.0000 &    2.0000 &    4.0000 &    4.0000 &    2.0000\\
9 &     4.0000 &    16.000 &    16.000 &    4.0000 &    4.0000 \\
10 &    16.000 &    16.000 &    4.0000 &    2.0000 &    4.0000 \\
11 &    4.0000 &    2.0000 &    3.0000 &    6.0000  &   6.0000\\
12 &    3.0000 &    6.0000 &    24.000 &    24.000 &    6.0000  \\
13 &    6.0000 &    24.000 &    24.000 &    6.0000 &    3.0000   \\
14 &    6.0000 &    6.0000 &    3.0000 &    4.0000 &    8.0000 \\
15 &    8.0000 &    4.0000  &   8.0000 &    32.000 &    32.000\\
16 &    8.0000 &    8.0000 &    32.000 &    32.000 &    8.0000 \\
17 &    4.0000 &    8.0000 &    8.0000 &    4.0000 &  \\
& & & & & \\

18 ~~~~(6)    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01 & 1.0000 E-01   \\
19 & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01 & 1.0000 E-01    & 1.0000 E-01  \\
20  & 1.0000 E-01    & 1.0000 E-01 &  1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01   \\
21 & 1.0000 E-01 & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01 \\
22    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01 & 1.0000 E-01   \\
23 & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01 &  1.0000 E-01    & 1.0000 E-01   \\
24 & 1.0000 E-01    & 1.0000 E-01 & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01   \\
25 & 1.0000 E-01  &  1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01 \\
26    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01 &  1.0000 E-01   \\
27 & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01 &  1.0000 E-01    & 1.0000 E-01   \\
28 & 1.0000 E-01    & 1.0000 E-01 & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01    \\
29 & 1.0000 E-01 &  1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01  \\
36    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01    & 1.0000 E-01 & \\
& & & & & \\
\hline\hline
\end{tabular}
}
\newline\\
\newline\\

\section{Running Statdose}

\subsection{Introduction}

\verb+STATDOSE+ can be invoked using the script {\em statdose}. It is
imperative that at least one dose distribution be read in before
attempting any type of analysis. After a distribution is loaded, it can be
normalized, rebinned, plotted and written to disk.  Statistical
comparisons can be performed if only two or more dose distributions have
been read in, and the voxel geometries (bin boundaries) are identical.\\

The following section outlines the \verb+STATDOSE+ options and explains
what each \verb+STATDOSE+ option will do and what input it requires. Most
options have default values which are listed in brackets beside the
prompt. In most cases, this default value is 0, which is synonymous with a
carriage return. Entering a default value will usually bounce the program
back to the previous menu. In the case where the required user input is a
character string, the default value listed beside the prompt will be set
by hitting carriage return.


\subsection{Read Dose Distributions}

The major features of the 'Read Dose Distributions' option are:

\begin{itemize}
\item the names of the {\em.3ddose} files (up to 40) in the current directory will be listed for the user
\item the routine will loop, prompting first for the number of the
file to read in, and then number under which to store it
\item up to 5 files can be read in
\item files can be read in at any time during a \verb+STATDOSE+ run
\item previously loaded  files can be overwritten
\item numbering of  file need not be consecutive
\end{itemize}

\subsection{Statistical Analysis}

In order to perform any of the statistical analysis routines, at least two
distributions must be loaded. The two distributions selected for
comparison must have the same structure (ie. the same number of bins and
the same bin boundary values). If either of these two conditions is not
met, the program will display a message and prompt the user for more
input. Statistical analysis includes calculation of the chi-squared/degree
of freedom and RMS deviations, the maximum absolute or percent difference in
dose and the
maximum dose along the central axis for the two distributions being
compared.  In addition, \verb+STATDOSE+ produces plots of the dose difference
or percent dose difference distribution and of the chi-squared distribution.

First, the user specifies whether he/she wishes to deal with a dose difference
distribution or a percent
dose difference distribution.
\verb+STATDOSE+ has 3 possible definitions for percent
dose difference.  Thus, the user has a total of 4 options:

{\bf Option 1} -- Plot frequency vs D1-D2

{\bf Option 2} -- Plot frequency vs (D1-D2)/[(D1+D2)/2)] * 100%

{\bf Option 3} -- Plot frequency vs (D1-D2)/[max avg central axis dose] * 100%

{\bf Option 4} -- Plot frequency vs (D1-D2)/SQRT(ERR1**2+ERR2**2)

Where D1 and D2 are the doses in the same voxel from the 2 distributions,
and ERR1 and ERR2 are the errors in D1 and D2 respectively.  Options 2 and 3
comprise the 3 different definitions of percent dose difference.  In Option 2,
the percentage difference is calculated with respect to the average of
D1 and D2.  Option 3 calculates the average with respect to the maximum
average (ie average between the 2 distributions) central axis (Z-axis) dose.
In Option 4, the difference
of Option 1 is scaled by the square root of the sum of the errors in the
two doses.  Note that if there are no systematic differences between
the two distributions, then we expect that Option 4 will produce a distribution
with a peak at $\sim$1.

After selecting the type of distribution, the user selects one of 3 possible
methods for scaling the plot.  The
equations used by \verb+STATDOSE+ to determine the binning structure for
each scaling option are listed below:\\

{\bf Option 1} -- Limit Frequency Distribution to Maximum Dose Difference or
Maximum Percent Dose Difference

\begin{equation}
W_{bin}= \delta_{max}/INT(n/2-1) \label{eq:option1}
\end{equation}

{\bf Option 2} -- Limit Frequency Distribution to Maximum Dose along the Central Axis

\begin{equation}
W_{bin}= D_{max}/INT(n/2-1)*10. \label{eq:option2}
\end{equation}

{\bf Option 3} -- Custom Bin Width

\begin{equation}
W_{bin}= user\ entered\ bin\ width \label{eq:option3}
\end{equation}

$W_{bin}$  is the calculated width of the bins (bin width can be a real
number), n is the number of bins desired (selected by the user),
$\delta_{max}$ is the maximum dose difference, and $D_{MAX}$ is the
maximum dose along the central axis. INT is the FORTRAN type cast to an
integer.  Note that Option 2 above, in which the plot is limited to the
maximum dose along the central axis, only makes sense if the user is plotting
a dose difference distribution and, thus, cannot be chosen if the
the user has selected one of the percent dose distributions.

The 2 sets of options described above apply only to the
dose difference distribution, not the chi-squared distribution.  The latter
is always calculated the same way, regardless of whether the user chooses
a dose difference or percent dose difference distribution, and is always
plotted on a scale from 0-10.
\\

For each of the program options, the user will be asked to select the number of a file or files on which to perform the appropriate action.


\subsection{Normalization}

This option asks the user to select the number of the data set to
normalize. The normalized dose distribution replaces the original dose
distribution and the product of the normalization factors applied to a
given distribution is stored. The original distribution is retrieved with
the 'denormalize' option, which divides the normalized distribution by the
stored factor. If the distribution has been rebinned, the result of
denormalization will be the original distribution, with all rebinning left
intact.

\begin{enumerate}
\item Apply Scaling Factor
\begin{itemize}
\item prompts user for a scaling factor
\item multiplies all the dose values in the distribution by this factor
\end{itemize}
\item Normalize to Average Dose
\begin{itemize}
\item finds the average dose for the distribution and the voxel where it occurs
\item each element of the dose array is divided by the average dose
\end{itemize}
\item Normalize to Maximum Dose Along Central Axis
\begin{itemize}
\item finds the maximum dose along the central axis of a distribution, and the voxel where it occurs
\item each element of the dose array is divided by the maximum dose
\end{itemize}
\item Normalize to Dose in Specific Voxel
\begin{itemize}
\item prompts the user for the coordinates of a voxel (enter 3 integers, separated by commas)
\item each element of the dose array will be divided by the dose in this
voxel
\end{itemize}
\item Denormalize
\begin{itemize}
\item reverses all normalizations performed on a dose distribution by dividing it by the stored cumulative normalization factor
\item denormalization will leave the binning structure intact
\end{itemize}
\end{enumerate}



\subsection{Rebinning}

This option allows the user to choose the number of the dose distribution
file  to rebin, as well as the number and name of the rebinned file for
plotting with {\tt xmgrace} . Rebinning modifies the size of the bins in
a dose distribution by a factor provided by the user. The rebinning factor
must be an integer. For instance, a rebinning factor of 4 condenses the
contents of 4 bins in the selected dose array into a single bin in a new
dose array. Dose values in the 4 bins will be added together and averaged
in order to calculate the new dose. Dose in any leftover bins will be
added and averaged (where appropriate) and placed in the last bin of the
new dose array. Currently, the routine only handles positive integral
rebinning factors, since it cannot perform any sort of data interpolation.
This means that the number of bins may only decrease (bins may only
increase in size).

\subsection{Plot}

The routine has two plot options, 'Plot Profiles' and 'Comparison Plot'.
Comparison Plot may be selected if there are two or more distributions
loaded. Both plot options allow several cross-plots or depth dose curves
to be plotted on a single graph. Curves which are parallel to the X and Y
axes are referred to as cross-plots, and those parallel to the Z axis are
depth-doses. Cross-plots and depth doses in which the curves are all
parallel to a single axis of voxel geometry are allowed, but combinations
of X,Y and Z axis plots {\bf cannot} be mixed on a single graph. Dose
values are plotted in the voxels which lie parallel to the axis selected
and pass through the selected coordinates.

\begin{enumerate}
\item Plot Profiles
\begin{itemize}
\item profiles all come from the same distribution
\item axis of profile must be an integer from 1-3, corresponding to X, Y and Z axes, respectively
\item graph title and output filename are arbitrary
\item number of curves must be an integer
\item prompts user for coordinates of each curve (enter 2 real numbers, separated by a comma)
\end{itemize}
\item Comparison Plot
\begin{itemize}
\item profiles come from different distributions
\item axis of profile must be an integer from 1-3, corresponding to X, Y and Z axes, respectively
\item prompts user for coordinates of the curve (enter 2 real numbers, separated by a comma)
\item graph title and output filename are arbitrary
\item if selected, automatic offset will slightly offset the location coordinate of the curves plotted, the dose values are unchange (default is no offset)

\end{itemize}
\end{enumerate}

Stored {\em plotname.xvparam} and {\em plotname.xvplt} files can be plotted by
{\tt xmgrace}  directly, without using STATDOSE. The appropriate command to
issue in order to retrieve the graph corresponding to these files is:\\
~\\
{\em xvgr -autoscale xy -type xydy -device  1 plotname.xvplt  -p
plotname.xvparam}


\subsection{Save}
Any dose distributions stored by the program can be saved. This means that
normalized and rebinned distributions can be written to disk in a format
that can be re-read by STATDOSE. The routine will display the names of all
loaded files and prompt the user for the number(s) and name(s) of the
file(s) to be stored. The current filename will be the default name under
which the distribution will be stored, so be careful that you do not wipe
out files that you meant to keep. This could happen if you attempt to save
a normalized distribution and get carried away when hitting carriage
returns!

\section{References}

\begin{enumerate}
\item  [{[1]}] Ma C.-M., Reckwerd P, Holmes M., Rogers D.W.O. and Geiser B.,
``DOSXYZ User's Manual'', {\it NRCC Internal Rep.} {\bf PIRS-0509 (B)} (1995)
\end{enumerate}


\end{document}
